---
layout: default
title: Getting Started
---

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h1 id="getting-started">Getting Started</h1>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        While the <a href="/learning/tutorial.html">tutorial</a> is the introduction to the language
        itself, this page helps you get started with the implementations.  If you want to link
        Jsonnet as a library, see <a href="/ref/bindings.html">bindings</a>.
      </p>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h2 id="interpreters">Interpreters</h2>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        The easiest way to execute some Jsonnet code is invoking an interpreter via the commandline
        as so:
      </p>
      <pre>jsonnet -e &lt;code&gt;</pre>
      <p>
        Or a filename:
      </p>
      <pre>jsonnet &lt;file&gt;</pre>
      <p>
        This dumps the JSON on stdout.  The tool is self-documenting with <tt>--help</tt>.  You can
        experiment with the Jsonnet files in the <a
        href="https://github.com/google/jsonnet/tree/master/examples">examples/</a> directory of the
        C++ Github repo.
      </p>
      <p>
        To get Jsonnet, you can build it from either the <a
        href="https://github.com/google/jsonnet">C++</a> or the <a
        href="https://github.com/google/go-jsonnet">Go</a> repositories.  See below for the
        differences between them.  Each repo has a README.md containing build instructions.
      </p>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h3 id="example">Example</h3>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>Evaluating a file.</p>

      <pre>$ jsonnet landingpage.jsonnet
{
   "person1": {
      "name": "Alice",
      "welcome": "Hello Alice!"
   },
   "person2": {
      "name": "Bob",
      "welcome": "Hello Bob!"
   }
}</pre>

      <p>Evaluating a snippet.</p>

      <pre>$ jsonnet -e '{ x: 1 , y: self.x + 1 } { x: 10 }'
{
   "x": 10,
   "y": 11
}</pre>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h3 id="text-output">Generating non-JSON output</h3>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        Sometimes it is useful to generate output that is not in JSON format. You can do this by
        writing Jsonnet code which evaluates to a string containing whatever your desired format
        is. When executed with <tt>jsonnet -S</tt> or <tt>jsonnet --string</tt> jsonnet will
        manifest the string result as plain text rather than a JSON-formatted string.
      </p>

      <pre>// ini_output.jsonnet
std.manifestIni({
  sections: {
    main: {
      host: "127.0.0.1",
      port: "9000",
    },
    database: {
      path: "/var/data",
    },
  },
})</pre>

      <p>
        When executed using <tt>jsonnet -S ini_output.jsonnet</tt>, this will output the generated
        INI formatted text directly.
      </p>

      <pre>$ jsonnet -S ini_output.jsonnet
[database]
path = /var/data
[main]
host = 127.0.0.1
port = 9000</pre>

    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h3 id="multi">Multiple File Output</h3>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        The Jsonnet commandline tool has a special mode for generating multiple JSON files from a
        single Jsonnet file.  This can be useful if you want to avoid writing lots of small Jsonnet
        files, or if you want to take advantage of cross-references and interdependencies between
        the files.  The idea is to create a single JSON structure, the top level of which defines
        the various files:
      </p>

      <pre>// multiple_output.jsonnet
{
  "a.json": {
    x: 1,
    y: $["b.json"].y,
  },
  "b.json": {
    x: $["a.json"].x,
    y: 2,
  },
}</pre>

      <p>
        When executed using <tt>jsonnet -m &lt;dir&gt;</tt>, this will write the generated JSON to
        files <tt>a.json</tt> and <tt>b.json</tt> in the given directory, instead of the whole thing
        being written to stdout.  In order to integrate nicely with build tools like <tt>make</tt>,
        the files are not touched if they already contain the given content.  To stdout is printed
        the list of target files, one per line.  This makes it easy to drive other tools that
        operate on the JSON files, e.g. via <tt>xarg</tt>.
      </p>

      <pre>$ jsonnet -m . multiple_output.jsonnet
a.json
b.json
$ cat a.json
{
   "x": 1,
   "y": 2
}
$ cat b.json
{
   "x": 1,
   "y": 2
}</pre>

    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h3 id="stream">YAML Stream Output</h3>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        Unlike JSON, YAML can represent several objects in the same file, separated by <tt>---</tt>.
        The Jsonnet commandline parameter <tt>-y</tt> causes the tool to expect the Jsonnet
        execution to yield an array.  Config designed for this mode typically looks like this:
        It then outputs that array as a sequence of JSON documents
        separated by <tt>---</tt>, which any YAML parser will interpret as a YAML stream.
      </p>
      <pre>// yaml_stream.jsonnet
local
  a = {
    x: 1,
    y: b.y,
  },
  b = {
    x: a.x,
    y: 2,
  };

[a, b]</pre>
      <p>
        When executed using <tt>-y</tt>, this will output that array as a sequence of JSON documents
        separated by <tt>---</tt> and terminated with <tt>...</tt>.  Any YAML parser <i>should</i>
        interpret this as a YAML stream (people have reported broken parsers, so try it out first).
      </p>
      <pre>$ jsonnet -y yaml_stream.jsonnet
---
{
   "x": 1,
   "y": 2
}
---
{
   "x": 1,
   "y": 2
}
...</pre>
    </div>
    <div style="clear: both"></div>
  </div>
</div>


<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <h2 id="cpp-or-go">C++, Go, or others?</h2>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

<div class="hgroup">
  <div class="hgroup-inline">
    <div class="panel">
      <p>
        There are multiple implementations of the Jsonnet interpreter. The original interpreter was
        written in C++. However, there is a newer implementation written in Go, and this generally
        has better performance, as well as the benefits of being written in a memory safe language.
        The Go implementation also includes a linter, which is not available in the C++ implementation.
        Both the C++ and Go versions are tested against the same test suite.
      </p>
      <p>
        Beyond the 'official' C++ and Go implementations, there are also various implementations written
        independently by other people, such as Rust and Haskell implementations, along with language
        bindings / wrappers for some other languages (such as PHP, and JavaScript).
        These are listed on the <a href="/ref/bindings.html#third_party_apis">Bindings</a> page.
      </p>
    </div>
    <div style="clear: both"></div>
  </div>
</div>

